Implement logic orchestration for Git Pull/Push operations #13518

wanling0000 · 2025-07-09T13:54:54Z

Final PR based on draft: JabRef#714

This PR implements the logic-layer orchestration for Git push and pull operations with semantic merging support. It enables JabRef to semantically merge .bib files when possible, avoiding manual conflict resolution for simple changes.

This is part of ongoing work to support full Git-based collaboration for .bib files. Further tests and UI integration are planned.

Steps to test

This PR implements the first part of Git sync support by enabling automatic semantic merges when there are no conflicts. The scenario is tested via TDD in GitSyncServiceTest, simulating the following steps:

Alice creates an initial commit and pushes it to the remote.
Bob clones the repo and modifies entry b, then pushes.
Alice modifies entry a, then pulls.
Since they changed different entries, we expect a clean merge without user intervention. The orchestrator is GitSyncService, and helper utilities and value objects are temporarily located in org.jabref.logic.git.util.

Documentation Supplement

🧩 Table: Git-related Class Responsibilities

Class	Responsibility
`GitSyncService`	Orchestrates Git operations (pull, merge, push). Handles conflict detection, semantic merging, and committing results.
`GitHandler`	Wrapper around JGit, provides high-level Git operations like fetch, commit, push, and branch management.

🔧 Key Methods in `GitSyncService`

Method	Purpose	Description
`fetchAndMerge(Path)`	Pulls and merges changes	Runs status checks, fetch, 3-way merge, conflict detection, and auto-commit. Invokes a UI conflict resolution strategy if needed.
`performSemanticMerge(...)`	Performs semantic 3-way merge	Compares base/local/remote `.bib` content semantically. Uses `SemanticMerger` and conflict resolution strategy.
`push(Path)`	Pushes local changes to remote	Based on sync status, decides whether to commit and push. Fails if unresolved conflicts exist.

📦 Package: `org.jabref.logic.git.io`

This package bridges Git and JabRef's BibTeX data model by handling read/write operations for .bib files at specific Git revisions.

Class	Responsibility
`GitFileReader`	Reads raw `.bib` text from a specific Git commit.
`GitFileWriter`	Writes `BibDatabaseContext` content back to a `.bib` file after merge.
`GitRevisionLocator`	Locates `base`, `local`, and `remote` commits for 3-way merge.
`RevisionTriple`	Data structure that holds the result of locating `base`, `local`, and `remote` revisions.

📦 Package: `org.jabref.logic.git.status`

Handles detection of Git repository and file tracking/sync status. Used before pull/push to determine the correct operation.

Class	Responsibility
`GitStatusChecker`	Static utility to check Git status of a `.bib` file and return a snapshot.
`GitStatusSnapshot`	Immutable snapshot of a file's Git tracking/conflict/sync state.
`SyncStatus`	Enum representing sync state (e.g., `UP_TO_DATE`, `BEHIND`, `DIVERGED`, etc.).

📦 Package: `org.jabref.logic.git.conflicts`

Handles semantic conflict detection and resolution strategies during 3-way merge.

Class	Responsibility
`SemanticConflictDetector`	Detects entry-level conflicts between base/local/remote `BibDatabaseContext`s.
`ThreeWayEntryConflict`	Data structure representing a single entry-level 3-way conflict.
`GitConflictResolverStrategy`	Interface for resolving conflicts — supports GUI/CLI strategies.
`CliConflictResolverStrategy`	CLI implementation (planned for JabKit, not yet integrated). GUI is currently prioritized.

Conflict Resolution Flow:

Detect conflicts with SemanticConflictDetector.
If conflicts exist, invoke a GitConflictResolverStrategy:
- In GUI: use GuiConflictResolverStrategy
- In future CLI: use CliConflictResolverStrategy
Apply merge plan if resolution succeeds.

📦 Package: `org.jabref.logic.git.merge`

Executes semantic 3-way merge operations on .bib files, including building merge plans and applying field-level changes.

Class	Responsibility
`MergePlan`	Represents semantic changes from base → remote to be applied to local.
`SemanticMerger`	Applies a `MergePlan` to a local `BibDatabaseContext`.
`GitSemanticMergeExecutor`	Interface defining a `performSemanticMerge()` contract.
`GitSemanticMergeExecutorImpl`	Default implementation of the above; invokes detector and merger.
`GitMergeUtil`	Utility class for low-level field and entry merging.

💡 GUI Module Integration Note

GUI dependencies are temporarily introduced to reuse the existing MergeEntriesDialog for conflict resolution.
This is injected via GitConflictResolverStrategy to keep the dependency direction correct (logic → gui).
A major UI refactor is WIP.

Class	Responsibility
`GuiConflictResolverStrategy`	GUI-based conflict resolution strategy. Reuses `MergeEntriesDialog` to let users manually resolve semantic conflicts in `BibEntry`s.

Mandatory checks

I own the copyright of the code submitted and I license it under the MIT license
[/] Change in CHANGELOG.md described in a way that is understandable for the average user (if change is visible to the user)
Tests created for changes (if applicable)
Manually tested changed features in running JabRef (always required)
[/] Screenshots added in PR description (if change is visible to the user)
Checked developer's documentation: Is the information available and up to date? If not, I outlined it in this pull request.
Checked documentation: Is the information available and up to date? If not, I created an issue at https://github.com/JabRef/user-documentation/issues or, even better, I submitted a pull request to the documentation repository.

jabgui/src/main/java/org/jabref/gui/autosaveandbackup/BackupManager.java

jabgui/src/main/java/org/jabref/gui/desktop/os/Linux.java

jabgui/src/main/java/org/jabref/gui/LibraryTabContainer.java

…esolver interface to the logic module) JabRef#12350

…itMergeUtil tests JabRef#12350

…ort-init

…abRef#12350

…remote main branch exists JabRef#12350

…Ref#12350

jablib/src/test/java/org/jabref/logic/git/GitSyncServiceTest.java

… main branch JabRef#12350

…jabref into clean-gsoc-git-support-init

jablib/src/test/java/org/jabref/logic/git/util/SemanticMergerTest.java

wanling0000 · 2025-07-30T13:30:55Z

In org.jabref.logic.git.conflicts, we need a package-info.java explaining the whole idea maybe :)

We need a test when this removes/ignores/... entries, because they don't have a cition key.
@article{,
  author = {test}
}
If possible, more tests should be added

case 3 in org.jabref.logic.git.conflicts.SemanticConflictDetector#detectConflicts seems to be untested (maybe related to my Windows machine and issues with non-closed git object)

Thanks, this comment really helped me realize a flaw in the current logic... 🥲

Right now, conflict detection relies entirely on citation key matching and only performs field-level comparison. Entry-level changes (like additions, deletions, or key changes) are only inferred indirectly via BibEntryDiff (e.g., via nulls), which risks missing edge cases.

I can fix this logic in the current PR by performing an explicit entry-level three-way comparison before checking for field-level conflicts. It might require an extra review of the updated SemanticConflictDetector and the test matrix.

Alternatively, I'm happy to keep this PR as is and address the logic fix in a separate PR right after this gets merged

Let me know what you prefer!

InAnYan · 2025-07-30T19:22:49Z

I think we with Oliver would really like to see this PR merged. So I think you can write new features in the follow up PR 😋

…ort-init

koppor · 2025-07-31T04:53:35Z

Regarding the algorithm: Maybe "just" using https://github.com/JabRef/jabref/blob/main/jablib/src/main/java/org/jabref/logic/bibtex/comparator/BibDatabaseDiff.java solves issues?

Merging this stats can later help to compare different approaches. Having the approaches here in the PR "hides" them between other discussions.

jablib/src/main/java/org/jabref/logic/git/merge/SemanticMerger.java

wanling0000 · 2025-08-01T14:02:13Z

Regarding the algorithm: Maybe "just" using https://github.com/JabRef/jabref/blob/main/jablib/src/main/java/org/jabref/logic/bibtex/comparator/BibDatabaseDiff.java solves issues?

Merging this stats can later help to compare different approaches. Having the approaches here in the PR "hides" them between other discussions.

Thank you! I’m currently using BibDatabaseDiff in SemanticConflictDetector to get remoteDiffs. But I now realize that to handle edge cases (e.g. entries without citation keys, or ones only changed in local), I also need to compute localDiffs.

Only relying on remoteDiffs plus the local map isn’t enough, because it would miss entries that are added or changed only in local.

I’ll revise the logic in the follow-up PR

…ort-init

trag-bot · 2025-08-01T14:40:49Z

@trag-bot didn't find any issues in the code! ✅✨

koppor · 2025-08-01T15:10:30Z

Retested on windows - added some fixes because of eclipse-jgit/jgit#155 (comment)

subhramit · 2025-08-01T16:58:06Z

Retested on windows - added some fixes because of eclipse-jgit/jgit#155 (comment)

~~I think you forgot to push?~~
Clarified over text - incoming follow-up. Will get this merged now.

addressed

* upstream/main: Issue 13619 Make Citation relations text more clear. (#13620) Explain how to handle notifications (#13630) Fix scope of 'determine issue number' job (#13627) Add proper closing (#13626) Implement logic orchestration for Git Pull/Push operations (#13518) Make pattern for issue number more strict Fix "Cannot load file MultiMergeEntries.fxml" (#13624) Add Copy markdown to copy citation (#13387) Add ADR-0047 (#13621) Initial start of implementing a LSP for integrity checks (#13612) Refactor merge entries package structure (#13614) New Crowdin updates (#13616) BibEntry class no longer implements Cloneable (#13615) Fix dark mode in {} of Citation Relations tab of the entry editor (#13609) Update dependency org.kohsuke:github-api to v2.0-rc.4 (#13611) Fix setting of proxy without password (#13605)

trag-bot bot reviewed Jul 9, 2025

View reviewed changes

jabgui/src/main/java/org/jabref/gui/autosaveandbackup/BackupManager.java Outdated Show resolved Hide resolved

trag-bot bot reviewed Jul 9, 2025

View reviewed changes

jabgui/src/main/java/org/jabref/gui/desktop/os/Linux.java Outdated Show resolved Hide resolved

trag-bot bot reviewed Jul 9, 2025

View reviewed changes

jabgui/src/main/java/org/jabref/gui/desktop/os/Linux.java Outdated Show resolved Hide resolved

koppor added component: git project: gsoc labels Jul 9, 2025

subhramit reviewed Jul 9, 2025

View reviewed changes

jabgui/src/main/java/org/jabref/gui/LibraryTabContainer.java Outdated Show resolved Hide resolved

subhramit mentioned this pull request Jul 9, 2025

WIP: GSoC Git Support - Support semantic pull merge without conflicts JabRef/jabref-koppor#714

Closed

4 tasks

wanling0000 added 9 commits July 14, 2025 01:50

init: add basic test case for git sync service

43ca5f7

feat(git): Add SemanticMerger MVP JabRef#12350

7fa3b86

feat(git): Implement normal sync loop without conflicts JabRef#12350

6233df9

chore(git): Apply review suggestions JabRef#12350

8d3fa2b

chore(git): Fix CI-related issues JabRef#12350

269473d

chore(git): Add push test + Fix failing unit test JabRef#12350

ac66eed

chore(git): Fix variable names + refactoring (moving the GitConflictR…

69575b5

…esolver interface to the logic module) JabRef#12350

refactor(git): Apply strategy pattern for conflict resolution + add G…

3fc49c3

…itMergeUtil tests JabRef#12350

fix: Repair failing unit tests and CI integration tests JabRef#12350

32c30a0

wanling0000 force-pushed the clean-gsoc-git-support-init branch from 8302ebc to 32c30a0 Compare July 14, 2025 00:54

wanling0000 added 5 commits July 14, 2025 02:09

Fix submodules

f8250d1

Merge remote-tracking branch 'upstream/main' into clean-gsoc-git-supp…

477cfae

…ort-init

test: Try to fix GitHandlerTest by ensuring remote main branch exists J…

61a19b8

…abRef#12350

test: Try to fix GitSyncServiceTest/GitStatusCheckerTest by ensuring …

7e36b2e

…remote main branch exists JabRef#12350

test: Try to fix GitSyncServiceTest by explicitly pushing refspec Jab…

cf60c02

…Ref#12350

trag-bot bot reviewed Jul 15, 2025

View reviewed changes

jablib/src/test/java/org/jabref/logic/git/GitSyncServiceTest.java Show resolved Hide resolved

wanling0000 and others added 7 commits July 15, 2025 18:56

Merge branch 'main' into clean-gsoc-git-support-init

bf05ce9

test: Try to fix GitSyncServiceTest by explicitly checking out to the…

5799483

… main branch JabRef#12350

Merge branch 'clean-gsoc-git-support-init' of github.com:wanling0000/…

36e7d95

…jabref into clean-gsoc-git-support-init

test: Try to fix GitSyncServiceTest JabRef#12350

9107ddf

Change exception logging

0ea08f1

Merge branch 'main' into clean-gsoc-git-support-init

bd2a738

test: Add debug output to GitSyncServiceTest JabRef#12350

a78c8c4

chore: Import Optional dependencies JabRef#12350

1052d4c

InAnYan reviewed Jul 30, 2025

View reviewed changes

jablib/src/test/java/org/jabref/logic/git/util/SemanticMergerTest.java Show resolved Hide resolved

wanling0000 added 2 commits July 30, 2025 20:34

chore: Apply review suggestions JabRef#12350

c371370

Merge remote-tracking branch 'upstream/main' into clean-gsoc-git-supp…

6f36b5c

…ort-init

fix: Replace BibEntry.clone() with copy constructor JabRef#12350

44c3fac

trag-bot bot reviewed Aug 1, 2025

View reviewed changes

jablib/src/main/java/org/jabref/logic/git/merge/SemanticMerger.java Show resolved Hide resolved

wanling0000 added 3 commits August 1, 2025 15:07

Merge remote-tracking branch 'upstream/main' into clean-gsoc-git-supp…

2f763f4

…ort-init

fix: Update import paths JabRef#12350

3aa5d23

retrigger CI

0319c09

wanling0000 requested review from subhramit, koppor and InAnYan August 1, 2025 15:04

koppor approved these changes Aug 1, 2025

View reviewed changes

subhramit approved these changes Aug 1, 2025

View reviewed changes

subhramit added this pull request to the merge queue Aug 1, 2025

Merged via the queue into JabRef:main with commit bfa37f0 Aug 1, 2025
1 check passed

github-actions bot mentioned this pull request Aug 1, 2025

Add (simple) git support #12350

Closed

JabRef deleted a comment from trag-bot bot Aug 1, 2025

koppor mentioned this pull request Aug 1, 2025

[Git integration] Add proper closing at testing #13626

Merged

2 tasks

Provide feedback

Saved searches

Use saved searches to filter your results more quickly

Uh oh!

Uh oh!

Implement logic orchestration for Git Pull/Push operations #13518

Implement logic orchestration for Git Pull/Push operations #13518

Uh oh!

wanling0000 commented Jul 9, 2025 •

edited

Loading

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

wanling0000 commented Jul 30, 2025 •

edited

Loading

Uh oh!

InAnYan commented Jul 30, 2025

Uh oh!

koppor commented Jul 31, 2025

Uh oh!

Uh oh!

wanling0000 commented Aug 1, 2025

Uh oh!

trag-bot bot commented Aug 1, 2025

Uh oh!

koppor commented Aug 1, 2025

Uh oh!

subhramit commented Aug 1, 2025 •

edited

Loading

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Implement logic orchestration for Git Pull/Push operations #13518

Implement logic orchestration for Git Pull/Push operations #13518

Uh oh!

Conversation

wanling0000 commented Jul 9, 2025 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Steps to test

Documentation Supplement

🧩 Table: Git-related Class Responsibilities

🔧 Key Methods in GitSyncService

📦 Package: org.jabref.logic.git.io

📦 Package: org.jabref.logic.git.status

📦 Package: org.jabref.logic.git.conflicts

📦 Package: org.jabref.logic.git.merge

💡 GUI Module Integration Note

Mandatory checks

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

wanling0000 commented Jul 30, 2025 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Uh oh!

InAnYan commented Jul 30, 2025

Uh oh!

koppor commented Jul 31, 2025

Uh oh!

Uh oh!

wanling0000 commented Aug 1, 2025

Uh oh!

trag-bot bot commented Aug 1, 2025

Uh oh!

koppor commented Aug 1, 2025

Uh oh!

subhramit commented Aug 1, 2025 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Uh oh!

Uh oh!

Uh oh!

wanling0000 commented Jul 9, 2025 •

edited

Loading

🔧 Key Methods in `GitSyncService`

📦 Package: `org.jabref.logic.git.io`

📦 Package: `org.jabref.logic.git.status`

📦 Package: `org.jabref.logic.git.conflicts`

📦 Package: `org.jabref.logic.git.merge`

wanling0000 commented Jul 30, 2025 •

edited

Loading

subhramit commented Aug 1, 2025 •

edited

Loading